home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Games / MAME / src / sound / pokey.txt < prev    next >
Text File  |  1997-02-04  |  14KB  |  320 lines
  1.                        Atari POKEY Chip Emulator V2.0
  2.                        ==============================
  3.                                 by Ron Fries
  4.                                   31 Jan 97
  5.  
  6. The PokeySound Chip Emulator is designed to emulate the functionality of the
  7. Atari POKEY Chip Hardware through 'C' Sourcecode.  The emulator is able to 
  8. produce sounds which are essentially identical to the original POKEY chip, 
  9. including the exact distortions and pitches. 
  10.  
  11. The emulator is designed to run in a 32-bit environment.  Though it can be
  12. compiled and run in a 16-bit environment, it is slow.  
  13.  
  14. I would like to give special thanks to Neil Bradley.  He provided excellent
  15. testing support and was also the driving force behind the multiple POKEY
  16. emulation.
  17.  
  18. New Features:
  19. -------------
  20.  
  21. Version 2.0 of the 'PokeySound' adds the following features:
  22.  
  23. 1) Support for multiple POKEY chips.  The maximum supported is configured
  24.    at compile time.
  25.  
  26. 2) An adjustable gain.  The previous releases had a built-in gain of 64.
  27.  
  28. 3) A clipping option.  Depending on the number of chips emulated and the
  29.    configured gain, it is possible for the output to exceed 8-bits.  
  30.    Clipping can be enabled to prevent this, though it does increase the
  31.    processing time. 
  32.  
  33.  
  34. Standard Features:
  35. ------------------
  36.  
  37. The 'PokeySound' emulator supports the following functions:
  38.  
  39. 1) All polynomial sound generators: 
  40.    a) 4-bit poly - actual bit pattern determined from sampled sound
  41.    b) 5-bit poly - actual bit pattern determined from sampled sound
  42.    c) 17-bit poly - simulated random bit pattern
  43.    d) 9-bit poly - derived from simulated 17-bit poly
  44.    
  45. 2) Full support of all 'Divide by N' counter clocks:
  46.    a) 1.79 MHz (high limited to playback sample rate)
  47.    b) 64 KHz (high limited to playback sample rate)
  48.    c) 15 KHz
  49.  
  50. 3) Full support of all 'Divide by N' resolutions:
  51.    a) 8-bit - single channel
  52.    b) 16-bit - double channel
  53.  
  54. 4) Full support of all distortions 
  55.    a) 5-bit poly, then 17-bit poly
  56.    b) 5-bit poly only
  57.    c) 5-bit poly, then 4-bit poly
  58.    d) 17-bit poly only
  59.    e) no poly counters (pure tone)
  60.    f) 5-bit poly only
  61.  
  62. 5) Full support of volume control 
  63.  
  64. 6) Full support of all pitches - distortions will vary exactly as the
  65.    original Atari based on different pitches
  66.  
  67. 7) Accurate pitch generation
  68.  
  69. 8) Support of any playback sample rate (e.g. 22050)
  70.  
  71.  
  72. The 'PokeySound' emulator does not currently support the following functions:
  73.  
  74. 1) High pass filters
  75.  
  76.  
  77. Though I don't believe adding support for the High-Pass filters is very
  78. complicated, I decided not to add support right now because I don't
  79. believe this feature is used much.  I'm also not sure how much impact it
  80. would have on performance.  Let me know if you find an application that
  81. uses it.
  82.  
  83. In the 2.0 release, I've removed the non-optimized vrersion.  It was only
  84. left in for reference.  If you would still like to see the non-optimized
  85. version, it's available in the 1.2 release.
  86.  
  87. One of the unique features of the emulator is that the processing time varies 
  88. based on the frequency.  Since the routine only calculates new output values 
  89. when a change is sensed, the lower frequencies (which change less frequently) 
  90. will require less processing time.
  91.  
  92.  
  93. Differences Between the Emulator and the Actual POKEY Chip:
  94. -----------------------------------------------------------  
  95.  
  96. The biggest difference between the emulator and the original hardware is 
  97. that the emulator emulates an 'ideal' POKEY chip.  All output from the 
  98. emulator is a based on a precise square wave, whereas the output from the
  99. original chip has decay.  Though the output is slightly different, I
  100. don't believe this difference is easily discernible.
  101.  
  102. Another slight difference is the 17-bit/9-bit poly.  Since the polynomial
  103. is large (2^17 bits), I choose to create the sample using a random number
  104. generator rather than a table.  I don't believe this difference is 
  105. significant.
  106.  
  107. There are also a few differences which are introduced by aliasing.  This is
  108. a direct result of using an output sampling rate which is not identical to
  109. the original sound rate.  It is most evident with high frequencies. 
  110.  
  111. A final difference is the lack of support for the High-Pass Filter 
  112. functionality.  I plan to add this in a future release if necessary.
  113.  
  114.  
  115. Sample/Test Application:
  116. ------------------------
  117.  
  118. The test program I've distributed is a 16-bit DOS application created with 
  119. the Borland 'C' compiler.  The only reason I used 16-bit was because I 
  120. already had a set of working SB drivers in 16-bit.  Since the test system
  121. is dedicated to generating sounds, the performance in 16-bit is more than
  122. adequate.
  123.  
  124.  
  125. POKEY.C
  126. =======
  127.  
  128. The POKEY.C file is the heart of the PokeySound Emulation program.  
  129. Although the routines in the file must work together, no other files are
  130. modules are required for operation.  A header file, 'POKEY.H', has 
  131. been included for use in other modules, and provides the necessary 
  132. function prototypes.  I've attempted to make the routines as portable as
  133. possible, so the file should compile on almost any compiler with little
  134. or no modification.  
  135.  
  136. I have made some attempts at optimizing the routines, though I am sure
  137. more optimization can be done.  They are currently only available in 'C'.
  138. I'll be happy to convert them to assembly language if desired.  Please feel 
  139. free to send me e-mail at rfries@tcmail.frco.com.
  140.  
  141. The routines are easy to use.  Detailed descriptions on the function calls   
  142. are listed below.
  143.  
  144. The POKEY.C module can be compiled in a 32-bit or 16-bit environment.
  145. Since these routines are optimized for 32-bit use, the code will default
  146. to 32-bit.  To compile in 16-bits, use a command line option to define
  147. the variable COMP16.
  148.  
  149.  
  150. GENERAL OVERVIEW
  151. ----------------
  152.  
  153. On start-up of the system, a single call should be made to Pokey_sound_init.  
  154. This routine will prepare the structures for sound output.  This routine
  155. can be called again if necessary during warm-start or other reset.
  156.  
  157. Once in the main loop, there are two other functions that will be used.  
  158. Whenever the system needs to write to either the AUDC or AUDF values,
  159. a call should be made to the Update_pokey_sound routine.  This routine will 
  160. take care of updating the internal registers.  It will pre-calculate several
  161. values to help with optimization.
  162.  
  163. The only other routine that is called is the Pokey_process function.  This 
  164. function will fill a audio buffer with a specified number of bytes.  This
  165. function should be called whenever a new audio buffer is required.
  166.  
  167. For best results, I recommend using at least two output buffers.  Using this
  168. scheme, the sound card can be playing one buffer while the system is filling
  169. the other.
  170.  
  171.  
  172. DETAILED FUNCTION DESCRIPTIONS
  173. ------------------------------
  174.  
  175. Pokey_sound_init(uint32 freq17, uint16 playback_freq, uint8 num_pokeys)
  176. -----------------------------------------------------------------------
  177.  
  178. This function initializes the structures used by the PokeySound routines.
  179. This function takes three parameters: the main clock frequency, the 
  180. playback frequency and the number of POKEY chips to emulate.
  181.  
  182. The maximum number of POKEY chips emulated is configured at compile time.
  183. Though the maximum number of chips can be configured as one, the PokeySound 
  184. 1.2 routines are recommended if only a single chip is to be emulated since 
  185. they have will provide better performance.  
  186.  
  187. The main clock frequency is the frequency of the 1.79MHz source clock.  
  188. To provide exact results, freq17 should be set equal to 1789790 Hz.  As an 
  189. alternative, freq17 can be set to an approximate frequency of 1787520 Hz.  
  190. Using this approximate frequency will reduce aliasing and thus produce a 
  191. clearer output signal.
  192.  
  193. A constant has been defined for both of these values for your convenience.
  194. The names are FREQ_17_EXACT and FREQ_17_APPROX.
  195.  
  196. The playback frequency is the frequency of the sound playback (the frequency 
  197. used by the sound card).  For best results, the playback frequency should 
  198. be an even division of the main clock frequency.  Since most of the sounds
  199. will be generated using the 64kHz clock, I also recommend making the 
  200. playback frequency an even division of the 64kHz clock.
  201.  
  202. The 64kHz clock is exactly equal to the main clock divided by 28.  For
  203. the playback frequency, I recommend one of the following values:
  204.  
  205. 1) FREQ_17_APPROX / (28*1), which is equal to 63840.  Of course, most sound 
  206.    cards can't reproduce this frequency.
  207.  
  208. 2) FREQ_17_APPROX / (28*2), which is equal to 31920.  All of the newer cards
  209.    will support this frequency.  
  210.  
  211. 3) FREQ_17_APPROX / (28*3), which is equal to 21280.  All of the SB 
  212.    compatibles should support this frequency.
  213.  
  214. 4) FREQ_17_APPROX / (28*4), which is equal to 15960.  This may be the
  215.    best choice, as it offers good sound reproduction with good performance.
  216.   
  217. Of course, these options also assume you are using the approximate
  218. frequency for the main clock as well.  Any of these choices will offer the
  219. best results when the main 64kHz clock is used, reasonable results when the
  220. 15kHz clock is selected, and marginal results when the 1.79MHz clock is
  221. selected (the only way to produce good results in all cases is to set the
  222. playback frequency to 1.79MHz!)
  223.  
  224. Feel free to experiment to find other alternatives as well.
  225.  
  226. This function has no return value (void).
  227.  
  228.  
  229. Update_pokey_sound (uint16 addr, uint8 val, uint8 chip, uint8 gain)
  230. -------------------------------------------------------------------
  231.  
  232. This function should be called each time an AUDC, AUDF or AUDCTL value
  233. changes.  This function takes four parameters: the address to change,
  234. the new value, the chip to be updated, and the gain to be used.  
  235. The lower four bits of the address should be one of the following values:
  236.  
  237.                   Addr     Description
  238.                  ------    -----------
  239.                   0x00        AUDF1
  240.                   0x01        AUDC1
  241.                   0x02        AUDF2
  242.                   0x03        AUDC2
  243.                   0x04        AUDF3
  244.                   0x05        AUDC3
  245.                   0x06        AUDF4
  246.                   0x07        AUDC4
  247.                   0x08        AUDCTL
  248.  
  249. In order to support multiple POKEY chips, only the lower four bits of
  250. the address are used.  Note that this routine can no longer be called with
  251. any address as it will affect the operation of the specified chip.
  252.  
  253. The routine pre-calculates several values that are needed by the 
  254. processing function.  This is done to optimize performance.
  255.  
  256. The output will be amplified (multiplied) by gain/16 (previous releases had 
  257. a built in multiplier of 4, which calculates to a gain value of 64).  If the 
  258. output exceeds the maximum value after then gain and clipping is enabled, 
  259. the output will be limited to reduce distortion.
  260.  
  261. The best value for the gain depends on the number of POKEYs emulated and
  262. the maximum volume used.  The maximum possible output for each channel is 15, 
  263. making the maximum possible output for a single chip to be 60.  Assuming all 
  264. four channels on the chip are used at full volume, a gain of 64 can be used 
  265. without distortion.  If 4 POKEY chips are emulated and all 16 channels are 
  266. used at full volume, the gain must be no more than 16 to prevent distortion.  
  267. Of course, if only a few of the 16 channels are used or not all channels are 
  268. used at full volume, a larger gain can be used.
  269.  
  270. To enable clipping, define the logical CLIP before compiling.  This is the
  271. default mode of operation as it has already been included in the POKEY.H file.
  272. Note that this is only recommended if clipping is necessary since it will 
  273. impact the performance.
  274.  
  275. This function has no return value (void).
  276.  
  277.  
  278. Pokey_process (uint8 *buffer, uint16 n)
  279. ---------------------------------------
  280.  
  281. This function calculates and fills a buffer with unsigned 8-bit mono audio.
  282. This function takes two parameters: a pointer to the buffer to fill and
  283. the size of the buffer (limited to 65535).  This function fills the 
  284. buffer based on the requested size and returns.  It automatically
  285. updates the pointers for the next call, so subsequent calls to this function
  286. will provide a continuous stream of data.
  287.  
  288. The size of the buffer that is needed depends on the playback frequency.
  289. It is best to keep the buffer as small as possible to maximize response time
  290. to changes in the sound.  Of course, the minimum size is dependent on
  291. system and emulator performance.
  292.  
  293. Selecting the correct buffer size is a careful balance.  Selecting a buffer
  294. size that is too small will produce noticeable clicks in the output, though
  295. selecting a size that is too large will cause a poor response time and 
  296. possible delays in the system when the new buffer is filled.
  297.  
  298. This function has no return value (void).
  299.  
  300.  
  301. License Information and Copyright Notice
  302. ========================================
  303.  
  304. PokeySound is Copyright(c) 1996-1997 by Ron Fries
  305.  
  306. This library is free software; you can redistribute it and/or modify it under 
  307. the terms of version 2 of the GNU Library General Public License as published 
  308. by the Free Software Foundation.
  309.  
  310. This library is distributed in the hope that it will be useful, but WITHOUT 
  311. ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
  312. FOR A PARTICULAR PURPOSE.  See the GNU Library General Public License for more 
  313. details.
  314.  
  315. To obtain a copy of the GNU Library General Public License, write to the Free 
  316. Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  317.  
  318. Any permitted reproduction of these routines, in whole or in part, must bear 
  319. this legend.  
  320.